home *** CD-ROM | disk | FTP | other *** search
- /*
- File: ExtensionsStrip.h
-
- Contains: Extensions Strip Specific Interfaces for Control Strip modules.
-
- Version: Technology: System 7.1+ (System 7.5+ preferred)
- Package: Extensions Strip 1.2
-
- Copyright: © 1995 by Ammon Skidmore, Skidperfect Software Inc.
- All rights reserved.
-
- Bugs?: If you find a problem, have a criticism or comment with this
- file, please inform the author at the following address:
- Internet: skidperfect@kagi.com
- */
-
- #ifndef __EXTENSIONSSTRIP__
- #define __EXTENSIONSSTRIP__
-
- #ifndef __CONTROLSTRIP__
- #include <ControlStrip.h>
- #endif
-
- #ifndef __APPLEEVENTS__
- #include <AppleEvents.h>
- #endif
-
- #ifdef __cplusplus
- extern "C" {
- #endif
-
- #if PRAGMA_ALIGN_SUPPORTED
- #pragma options align=mac68k
- #endif
-
- #if PRAGMA_IMPORT_SUPPORTED
- #pragma import on
- #endif
-
-
- /******************************************************************************************
-
- Special Extensions Strip selector calls to modules.
-
- ******************************************************************************************/
- enum {
- sdevInAppContext = 2000, /* called only once after the module specifically
- requested to be executed from inside Extension
- Strip's context. NB: you can return the special
- result values. */
-
- sdevInterceptedEvent = 2001, /* if the module returned the sdevInterceptAllEvents
- flag in its features, then this selector
- will get called before _each_ event is processed
- by Extensions Strip. Meant to be used with
- _SBGetCurrentEvent so each event can be looked at,
- and modified if necessary (to prevent passing.)
- NB: you can return the special result values. */
-
- sdevDragAccept = 2002, /* return 0 if you accept the current drag, and
- 1 if you do not. Modules that do not have any
- drag handlers will never get this called.
- NB: sdevDragAccept is only called from within
- Extensions Strip's dragTrackingInWindow. So it
- is recommended to only check if you accept the
- drag from within your dragTrackingEnterWindow, and
- then set a global var that you can pass onto ES */
-
- sdevEventMask = 2003 /* if the module returned the sdevInterceptAllEvents
- flag in its features, this selector will get
- called to find the event mask to use. Return your
- mask as the result value of the sdev call.
- sdevEventMask is called once upon initialization,
- and every time sdevFeaturesChange is requested. */
- };
-
- /******************************************************************************************
-
- Features supported by the module. If a bit is set, it means that feature is supported.
-
- Tip: if you clear sdevWantMouseClicks and set sdevDontAutoTrack, your module
- will receive clicks and Extensions Strip (plus Desktop Strip) will not
- auto-hilite your module.
-
- ******************************************************************************************/
- enum {
- sdevHasDragHandlers = 31, /* module has installed a drag tracking and/or
- receive handler in the Strip window. */
-
- sdevDontPeriodicTickle = 30, /* module does not require any idle time so
- by setting this bit it will never get
- called with the sdevPeriodicTickle
- selector. Note that you can set this along
- with the sdevInterceptAllEvents bit (if you want)
- and sdevInterceptedEvent will still get called.
- So be nice and set this to help speed up idle
- time processing. */
-
- sdevInterceptAllEvents = 29 /* module wants to be executed before each
- event passes through Extension Strip's
- jGNE filter. Because the module is allowed
- to modify every event, there is no more need
- for modules, such as Terminator Strip, to
- install their own jGNE filters!
- NB: You need to return an event mask when your
- module is called by the sdevEventMask selector. */
- };
-
- /******************************************************************************************
-
- Special result values returned by the sdevPeriodicTickle and sdevMouseClick selectors.
- If a bit is set, the module can request that a specific function is performed by
- the Control Strip. All undefined bits should be set to zero.
-
- Note: these values can also be returned by the sdevInAppContext and
- sdevInterceptedEvent selectors.
-
- ******************************************************************************************/
- enum {
- sdevQueueModule = 31, /* module needs to be executed from within
- Extension Strip's context: useful for
- things like sending AppleEvents or
- creating and tracking new drags. */
-
- sdevFeaturesChange = 30 /* module wants to change its feature flags. Useful
- for changing clickable state of the module and
- for locking/unlocking the sdev code. */
- };
-
- /******************************************************************************************
-
- miscellaneous
-
- ******************************************************************************************/
- enum {
- kModuleFolderType = 'sdev', /* FindFolder type for the root folder */
- kModuleDisabledFolderType = 'sdeD', /* FindFolder type for the disabled
- root folder (place to put inactive
- modules that you don't want deleted.) */
- sdevTypeCodePPC = 'Sdev' /* resource type for PPC module code */
- };
-
-
- enum {
- gestaltExtensionsStripAttr = 'CsEs', /* returns Extensions Strip's attributes. */
- /* currently returned bits from gestaltExtensionsStripAttr: */
- gestaltExtensionsStripExists = 0, /* Extensions Strip is currently launched */
- gestaltSupportsFontTraps = 1, /* The new font traps of Control Strip 1.2
- are supported. ES 1.0 incorrectly gave
- Control Strip's font trap gestalt bit. */
- gestaltHasSBResolveAliasFile = 2, /* ES contains the new alias resolving trap.
- This bit also signifies that ES can only
- be run as a regular application. */
-
- gestaltDesktopStripAttr = 'CsWT' /* returns the Desktop Strip program
- attributes which are supported by
- Extensions Strip. See Desktop Strip's
- docs for details about the bits */
- };
-
-
- typedef unsigned long ModuleReference;
-
-
- typedef pascal void (*SBQueueProcPtr)(unsigned long refCon);
-
- #if GENERATINGCFM
- typedef UniversalProcPtr SBQueueUPP;
- #else
- typedef SBQueueProcPtr SBQueueUPP;
- #endif
-
- enum {
- uppQueueProcProcInfo = kPascalStackBased | STACK_ROUTINE_PARAMETER(1, kFourByteCode)
- };
-
- #if GENERATINGCFM
- #define NewSBQueueProcProc(userRoutine) \
- (SBQueueUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppAEIdleProcInfo, GetCurrentArchitecture())
- #else
- #define NewSBQueueProcProc(userRoutine) \
- ((SBQueueUPP) (userRoutine))
- #endif
-
- /******************************************************************************************
-
- Control Strip trap calls
-
- ******************************************************************************************/
-
- // //
- // All routines are documented as to whether the Extensions Strip implementation //
- // of them they may move memory. You can trust that a routine that says it //
- // will not move memory in this version, will not move memory in future versions.//
- // Note though, that some Universal Control Strip traps may move memory under //
- // Control/Desktop Strip but not in Extensions Strip (such as //
- // _SBIsControlStripVisible and _SBShowHideControlStrip.) //
- // //
-
- // =====================================================
- // =========== Universal Control Strip traps ===========
- // =====================================================
- /*
- 'Yes' = May move memory!
- 'No' = Will not move memory.
- 'unimplemented' = Trap not supported by Extensions Strip when this header file
- was released. Check the Control Strip gestalt features to
- determine if/when Extensions Strip supports these traps.
-
- SBIsControlStripVisible no
- SBShowHideControlStrip no
- SBSafeToAccessStartupDisk no
- SBOpenModuleResourceFile yes
- SBLoadPreferences yes
- SBSavePreferences yes
- SBGetDetachedIndString no
- SBGetDetachIconSuite yes
- SBTrackPopupMenu yes
- SBTrackSlider yes
- SBShowHelpString yes
- SBGetBarGraphWidth no
- SBDrawBarGraph yes
- SBModalDialogInContext yes
-
- Control Strip 1.2 and later
- ---------------------------
- SBGetControlStripFontID no
- SBSetControlStripFontID no
- SBGetControlStripFontSize no
- SBSetControlStripFontSize no
- SBGetShowHideHotKey unimplemented
- SBSetShowHideHotKey unimplemented
- SBIsShowHideHotKeyEnabled unimplemented
- SBEnableShowHideHotKey unimplemented
- */
-
- // =====================================================
- // ========== Extensions Strip specific traps ==========
- // =====================================================
-
- /* Strip Window Utilities */
-
- // returns: true = vertical; false = horizontal
- // // Will not move memory. //
- extern pascal Boolean SBIsControlStripVertical(WindowRef stripPort)
- TWOWORDINLINE(0x70FF, 0xAAF2);
-
- // returns pixel depth of the monitor this Strip window is in (always a power of 2)
- // // Will not move memory. //
- extern pascal short SBGetControlStripDepth(WindowRef stripPort)
- TWOWORDINLINE(0x70FE, 0xAAF2);
-
- // returns the current normal back color of this Strip window
- // // Will not move memory. //
- extern pascal void SBGetStripBackColor(RGBColor *color, WindowRef stripPort)
- TWOWORDINLINE(0x70FD, 0xAAF2);
-
- //returns the current back color of this Strip window when a module is selected
- // // Will not move memory. //
- extern pascal void SBGetStripSelectedColor(RGBColor *color, WindowRef stripPort)
- TWOWORDINLINE(0x70FC, 0xAAF2);
-
- /* Module Utilities */
-
- // returns a reference number that all of the Module Utilities need
- /* NB: since SBGetMyReferenceNum can ONLY be called from sdevInitModule,
- you should save its value into your globals if you are going to use
- one of the Module Utilities later, such as inside a tracking handler. */
- // Also, the reference number will always be non-zero.
- // // Will not move memory. //
- extern pascal ModuleReference SBGetMyReferenceNum(void)
- TWOWORDINLINE(0x70FB, 0xAAF2);
-
- // total window space taken up by a module. Useful for drag-n-drop calculations
- // note that this rect will always be larger than the module's statusRect.
- // // Will not move memory. //
- extern pascal void SBGetTotalModuleBounds(Rect *bounds, WindowRef stripPort, ModuleReference moduleRefNum)
- TWOWORDINLINE(0x70FA, 0xAAF2);
-
- // returns the statusRect of the module. Very useful for drag-n-drop routines
- // because you no longer have to constantly set a global rectangle variable to
- // hold the current location of the module in the Strip window.
- // // Will not move memory. //
- extern pascal void SBGetModuleBounds(Rect *bounds, ModuleReference moduleRefNum)
- TWOWORDINLINE(0x70F9, 0xAAF2);
-
- /* Miscellaneous Utilities */
-
- // runs this (locked!) piece of code once within Extensions Strip's context.
- // PPC modules must pass a valid routine descriptor to this function. Since
- // the descriptor will not be disposed of after the code has executed, I would
- // recommend creating the descriptor (NewSBQueueProcProc) when sdevInitModule
- // is called and disposing it upon sdevCloseModule.
- // A non-zero result code means that the UPP could not be queued (memory error).
- // // May move memory! //
- extern pascal OSErr SBQueueCode(SBQueueUPP theProc, unsigned long refCon)
- TWOWORDINLINE(0x70F8, 0xAAF2);
-
- // sends the specified Apple Event within Extensions Strip's context to insure
- // safe sending rather than trusting that the front application is AE aware.
- // _SBSimpleAESend acts just like _AESend in that the AppleEvent you give to it
- // must still be disposed of afterward by your code to free up memory (even
- // though the event hasn't actually been sent yet.)
- //
- // _SBSimpleAESend is meant to be an easy way to send simple events. If you
- // need to check the reply AppleEvent or the _AESend error, ect., you should queue
- // your code (with _SBQueueCode or by having your module return 'sdevQueueModule')
- // and send the Apple Event yourself. The result returned by _SBSimpleAESend
- // is only non-zero if an error occured while queueing the event for later sending.
- //
- // Also, if an error does occur when Extensions Strip sends your AppleEvent, the
- // user will be notified with a dialog that _AESend failed.
- //
- // Here are the parameters I give to _AESend. They are basic enough for most
- // kinds of Apple Events that modules send, hence the name _SBSimpleAESend.
- // err = AESend(&theAppleEvent, &reply, // your specified AppleEvent
- // // and a dummy reply descriptor
- // kAENoReply + kAEAlwaysInteract + kAECanSwitchLayer, // send mode
- // kAENormalPriority, // send priority
- // kAEDefaultTimeout, // time out
- // nil, // idleProc
- // nil); // filterProc
- // // May move memory! //
- extern pascal OSErr SBSimpleAESend(const AppleEvent *theAppleEvent)
- TWOWORDINLINE(0x70F7, 0xAAF2);
-
- // returns a pointer to the current event being processed. Modififations to
- // the data in this pointer WILL take effect as the event gets passed along
- // to the other processes and jGNE filters further on in the chain. Although
- // a module can use this function at any time, it is really meant to be called
- // within the sdevInterceptedEvent selector because this is where a module can
- // deny other modules the proper processing of the event (such as in the case
- // of a keyDown.) Another good use for SBGetCurrentEvent() is to find the exact
- // point where a mouseDown occured if you have a queue of clickable objects.
- // // Will not move memory. //
- extern pascal EventRecord* SBGetCurrentEvent(void)
- TWOWORDINLINE(0x70F6, 0xAAF2);
-
- // For Extensions Strip 1.2 and later. //
- // Check for gestalt features bit 'gestaltHasSBResolveAliasFile'. //
-
- // resolves a chain of alias files just like the toolbox routine ResolveAliasFile()
- // but with an option to override the mounting of remote volumes. Most of the code
- // is from an Apple snippet in the Technote "Quietly Resolving Finder Aliases".
- //
- // Also, in the event of the display of an AppleShare mounting dialog, if the
- // current process is not in front, then the front process will be set to the
- // current one. Since Extensions Strip 1.2 and later can only be run as regular
- // applications, the use of this trap is almost always safe to display mount
- // dialogs. You should, however, set the mounting of remote volumes to false
- // if called inside a drop handler when the current process is not the front one.
- // // May move memory! //
- extern pascal OSErr SBResolveAliasFileMountOption(FSSpec *fileFSSpec, Boolean resolveAliasChains,
- Boolean *targetIsFolder, Boolean *wasAliased, Boolean mountRemoteVols)
- TWOWORDINLINE(0x70F5, 0xAAF2);
-
-
- #if PRAGMA_IMPORT_SUPPORTED
- #pragma import off
- #endif
-
- #if PRAGMA_ALIGN_SUPPORTED
- #pragma options align=reset
- #endif
-
- #ifdef __cplusplus
- }
- #endif
-
- #endif /* __EXTENSIONSSTRIP__ */
-